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玩 Ruby 也 有 段 时 间 了 ， 作 为 半 个 Rubist 最 近 在 学 习 编写 Ruby 的 C 扩 展 时 发 现 相 关 的 资料 非常 的 少 。 首 先是 在 Ruby 的 官方 文 
档 中 没有 相关 的 介绍 ， 其 次 是 网 上 相关 的 介绍 也 很 少 。 好 不 容易 在 《Programming Ruby》 中 找到 了 一 点 资料 也 是 Ruby1.8 
的 ， 有 些 内 容 已 经 不 能 用 了 ， 不 过 还 是 有 些 参考 价值 的 。 


作为 一 个 程序 员 ， 没 有 文档 是 件 很 纠结 的 事 。 关 于 这 点 我 觉得 Python 就 比较 好 。Python 的 官方 文档 不 仅 详细 ， 而 且 还 有 例 
于 5 


经 过 了 一 段 时 间 的 折腾 ， 现 在 大 致 也 有 所 了 解 了 。 于 是 乎 准备 把 这 些 内 容 整 理 一 下 ， 然 后 就 有 了 这 本 电子 书 。 当 然 如 果 要 在 
Ruby 中 调用 C， 现 在 来 说 可 以 有 多 种 方法 实现 。 而 直接 使 用 C 来 编写 Ruby 扩 展 的 方法 显得 略 有 些 过 时 了 ， 但 是 不 管 怎样 它 也 
是 一 种 比较 有 效 的 方法 。 

同时 本 文 的 示例 的 代码 均 可 从 我 的 Github 获 取 到 : https://github.comAwusuopu/ruby-c-extension-sample 

注意 : 在 编写 本 书 时 最 新 版 的 ruby 是 2.1.0 版 本 。 


最 后 ， 如 果 觉 得 本 文 对 您 有 用 ， 欢 迎 捐赠 。 


我 的 比特 币 地 址 : 1N4NES3183t2tU64aGbkotCmRYymJ1UDn6 


一 个 简单 的 例子 


目录 结构 


首先 介绍 一 下 ruby 项 目的 代码 目录 结构 。 通 常情 况 下 一 个 ruby 扩 展 项 目的 目录 结构 如 下 : 


NEWS 
Rakefile 
README.rdoc 
doc/ 

ext/ 


COPYING 为 版 权 信息 ; NEWS 包含 了 发 行 信息 ; Rakefile 定义 了 rake 任 务 ; README.rdoc 包含 了 用 于 生成 RDoc 文 档 的 头 部 信 
息 ; doc 目录 下 为 该 项 目的 文档 ; ext 目录 下 为 扩展 程序 的 源 代 码 以 及 extconf.rb 文件 。 以 上 人 为 参考 ， 实 际 中 还 需 根 据 自己 
的 情况 新 增 或 者 减少 一 些 文件 。 


MKMF 


MKMF 是 ruby 扩 展 构建 系统 的 一 部 分 ， 它 用 于 生成 编译 C 程 序 所 需 的 头 文件 和 Makefile 文 件 。 通 常 该 脚本 的 文件 名 为 : 
extconf.rb ， 这 个 有 点 类 似 于 python 中 的 setup.py 脚本 。 以 下 是 一 个 简单 的 例子 : 


require 'mkmf' 
RbConfig::MAKEFILE_CONFIG['CC'] = ENV['CC'] if ENV['CC'] 
extension_name = 'example' 
unless pkg_config('library') 
raise "library not found" 


end 


have func('some function', 'library/lib.h') 
have_type('some type', 'library/lib.h') 


create_header 
create_makefile(extension_name) 


第 1 行 导入 了 mkmf 模 块 ; 
第 5 行 定义 了 该 扩展 模块 的 名 称 ; 
第 7 到 9 行 调用 pkg-config 检 查 所 需 的 库 是 否 存在 ; 


第 11 行 调用 have_func 方法 检查 在 对 应 的 库 中 some _function 方法 是 否 已 定义 ， 如 果 存 在 则 会 在 生成 的 extconf.h 文件 中 定义 一 
个 名 为 HAVE_ 的 宏 ; 


第 12 行 调用 have_type 方法 检查 在 对 应 的 库 中 some_type 结构 体 是 否 已 定义 ， 如 果 存 在 则 会 在 生成 的 extconf.h 文件 中 定义 一 
个 名 为 HAVE_TYPE_ 的 宏 ; 


第 14 行 创建 extconf.h 头 文 件 ; 
第 15 行 创建 Makefile 文件 。 


extconf.rb 脚本 编写 完成 之 后 ， 可 以 执行 如 下 命令 使 用 : 


$ cd ext 
$ ruby extconf.rb 
$ make 


Rakefile 


extconf 脚本 创建 完了 ， 接 下 来 是 创建 Rakefile 。 顾 名 思 义 Rakefile 就 是 ruby 的 Makefile， 即 就 是 用 ruby 来 编写 Makefile 的 功 
能 。 以 下 是 一 个 简单 的 例子 : 


require "rake/clean' 


EXT_CONF = 'ext/extconf.rb' 
MAKEFILE = 'ext/Makefile' 
MODULE = 'ext/example.so' 
SRC = Dir.glob('ext/*.c') 
SRC << MAKEFILE 


CLEAN.include [ 'ext/*.0', 'ext/depend', MODULE ] 
CLOBBER.include [ 'config.save', 'ext/mkmf.log', 'ext/extconf.h', MAKEFILE ] 


file MAKEFILE => EXT_CONF do 人 tl 
Dir::chdir(File::dirname(EXT_CONF)) do 
unless sh "ruby #{File::basename(EXT_ CONF)}" 
$stderr.puts "Failed to run extconf" 
break 
end 
end 
end 
file MODULE => SRC do |t| 
Dir::chdir(File::dirname(EXT_CONF)) do 
unless sh "make" 
$stderr.puts "make failed" 
break 
end 
end 
end 
desc "Build the native library" 
task :build => MODULE 


第 9 行 和 第 10 行 分 别 设置 了 要 删除 的 文件 的 列表 。 cLEAN 变量 中 定义 的 文件 列表 会 在 rake clean 命令 中 被 删除 ; CLOBBER 变量 
中 定义 的 文件 列表 会 在 rake clobber 命令 中 被 删除 。 


从 第 12 行 到 29 行 定义 了 build 任务 ， 用 于 生成 扩展 模块 。 


程序 示例 


接 下 来 通过 一 个 简单 的 例子 来 介绍 C 扩 展 的 编号。 创建 一 个 新 文件 my_test.c 内 容 如 下 : 


#include "ruby.h" 


static VALUE mTest; 
static VALUE cTest; 


static VALUE t_init(VALUE self) 
i 


printf("\nCreate a MyTest instance.\n"); 


return self; 


上 


void Init_my_test() 

{ 
mTest = rb_define_module("MyTest"); 
cTest = rb_define_class_under(mTest, "MyTest", rb_cObject); 
rb define_method(cTest, "initialize", t_init, 0); 


} 


第 1 行将 ruby 的 头 文 件 导 入 进来， 以 便 能 使 用 ruby 的 api。 


在 该 程序 代码 中 定义 一 个 特殊 的 函数 Init_my test ， 它 是 该 模块 的 初始 化 函数 ， 在 模块 首次 加 载 时 执行 。 每 个 C 扩 展 都 需要 定 
义 一 个 名 为 Init_<name> 的 函数 ， 这 与 Python 的 C 扩 展 相 似 。 


在 Init_my test 辑 数 内 部 使 用 rb_define_module 男 数 定义 了 一 个 名 为 MyTest 的 Module， 然 后 再 用 rb_define_class_under 酚 数 
为 该 Module 定 义 了 一 个 类 MyTest 。 并 且 对 应 的 初始 化 画 数 为 t_init 。 


e rb_define_module : 定义 一 个 Module ; 
e rb_define_class_under : 在 一 个 Module 内 定义 一 个 Class ; 
e rb_define_method : 定义 一 个 实例 方法 ， 所 需 的 参数 依次 为 类 对 象 、 方 法 名 、 对 应 的 C 画 数 以 及 参数 个 数 ; 


注意 : 所 有 被 Ruby 调 用 的 C 方 法 都 必须 返回 一 个 VALUE 类 型 的 变量 。 


以 上 这 段 代 码 等 效 于 如 下 ruby 代 码 : 


module MyTest 
class MyTest 
def initialize 
puts "\nCreate a MyTest instance." 
end 


程序 写 完 之 后 运行 命令 : rake build 进行 编译 。 


最 后 再 通过 一 个 小 程序 来 进行 测试 : 


# app.rb 
require "./my_test.so" 
require "test/unit" 


class TestTest < Test::Unit::TestCase 
def test test 
t= MyTest::MyTest.new 
assert_equal(Object, MyTest::MyTest.superclass) 
assert_equal(MyTest::MyTest, t.class) 
end 
end 
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定义 函数 

在 上 一 节 的 例子 中 简单 提 到 了 使 用 rb_ define_method 来 定义 一 个 函数 。 在 这 一 节 来 进行 详细 介绍 。 
首先 ， 画 数 有 两 种 类 型 : 


e 参数 个 数 固定 ; 
e 参数 个 数 可 变 。 


然后 ， 以 下 是 rb_define_method 的 基本 用 法 : 
rb_define_method(ClassObj, "name", c_function, num); 


执行 的 结果 是 为 ClassObj 这 个 类 定义 一 个 名 为 name 的 实例 方法 ， 对 应 的 C 画 数 为 c_function， 接 收 num 个 参数 。 
e 若 num 的 值 为 正 数 ， 则 表示 需要 传人 num 个 参数 ; 
e 若 num 的 值 为 负数 ， 则 表示 该 方法 的 参数 个 数 是 可 变 的 ; 


o num 为 -1, 则 传 入 的 参数 是 一 个 C 的 数组 ; 
o num 为 -2, 则 传人 的 参数 是 一 个 Ruby 的 数组 。 


固定 参数 


对 于 参数 个 数 固定 的 情况 ， 它 对 应 的 c_function 基本 形式 如 下 : 


VALUE c_function(VALUE self, VALUE arg1, VALUE arg2) 


uy 
We 
1 


其 中 self 为 该 方法 的 调用 者 ， 其 余 的 均 是 该 方法 的 参数 。 


可 变 参 数 
可 变 参数 又 分 为 两 种 情况 : 传 入 的 是 C 数 组 和 传 入 的 是 Ruby 数 组 。 


C 数 组 


对 于 第 一 种 情况 ， 它 对 应 的 c_function 基本 形式 如 下 : 


VALUE ¢c function(int argc, VALUE *argv, VALUE self) 


{ 
Be 
这 种 情况 比较 复杂 。 


e@ argc 为 传人 参数 的 个 数 ; 
e argv 为 传人 参数 的 集合 ; 
e@ self 为 方法 调用 者 。 


对 于 这 种 情况 不 要 直接 对 argv 进行 操作 ， 而 是 使 用 rb_scan_args 方法 : 


rb_scan_args(argc, argv format, ...); 


rb_scan_args 是 通过 format 字符 串 指定 的 格式 对 argv 进行 解析 ， 当 参数 不 匹配 时 会 抛 出 异常 。 


下 面 通过 与 之 等 效 的 ruby 代 码 来 介绍 一 下 format 的 用 法 : 


def foo( arg = nil ) 
rb_scan_args(argc, argv， "01", &arg); 


这 是 定义 了 一 个 方法 ， 有 0 个 必须 参数 和 1 个 可 选 参数 ; 


def foo( Sblock ) 
rb_scan_args(argc, argv "0&", &block); 


这 是 定义 了 一 个 方法 ， 需 要 一 个 block 类 型 的 参数 ; 


def foo( *args ) 
rb_scan_args(argc, argv, "0*", &args); 


这 是 定义 了 一 个 方法 ， 可 传人 任意 个 数 的 参数 ; 


def foo( arg, opt = nil, *args, &block ) 
rb_scan_args(argc, argv, "11*&", &arg, &opt, &args, &block); 


最 后 这 是 对 上 面 的 整合 。 


Ruby 数 组 


这 种 情况 比较 简单 ， 它 对 应 的 c_function 形式 如 下 : 


VALUE c_function(VALUE self, VALUE args) 


{ 
WA 


上 


这 里 所 有 的 参数 都 放 在 ruby 类 型 的 数组 args 中 。 


对 象 类 型 


在 Ruby 中 一 切 都 是 对 象 ， 在 C 语 言 中 要 访问 Ruby 的 对 象 是 通过 VALUE 类 型 


Ruby 中 定义 了 一 些 内 建 的 类 型 ， 由 于 文档 中 没有 介绍 ， 下 面 的 这 些 内 容 都 是 


表 如 下 : 


eT_NONE 
eo T_NIL 
eT_OBJECT 
eT_CLASS 
。T_ICLASS 

eT_ MODULE 
eT_FLOAT 
eT_STRING 
。T_REGEXP 
eT_ARRAY 
eT_HASH 
eT_STRUCT 
。T_BIGNUM 
eT_FILE 
eT_FIXNUM 
。 T_TRUE 
eT_FALSE 
。T_DATA 
eT_MATCH 
eT_SYMBOL 
eT_RATIONAL 
eT_COMPLEX 
eT_UNDEF 
eT_NODE 

eT ZOMBIE 
eT_MASK 


同时 C 的 api 也 提供 了 一 些 方法 用 于 检测 对 象 的 类 型 : 
eintTYPE(obj) 返回 obj 对 象 所 属 的 内 建 类 型 ; 


e void Check_Type(VALUE obj, inttype) 检查 对 象 obj 是 否 属 于 type 类 型 
e char* rb_obj_classname(obj) 返回 对 象 obj 所 属 的 类 的 名 字 ; 





接 下 来 再 介绍 一 下 几 种 常用 数据 类 型 及 其 相关 的 api。 
Numbers 


在 Ruby 中 有 两 种 数字 类 型 : Fixnum 和 Bignum。 与 数字 相关 的 一 些 api 有 : 


的 变量 进行 引用 的 。 


我 直接 从 源 代码 的 ruby.h 头 文件 中 出 来 的 。 列 


， 如 果 不 属于 则 会 抛 出 异常 ; 


接口 描述 
INT2FIX(i) 将 int 类 型 转化 为 Fixnum 对 象 
INT2NUM(i) 将 int 类 型 转化 为 Fixnum 对 象 或 者 Bignum 对 象 
LONG2FIX(i) 与 INT2FIX 相 似 
LONG2NUM(i) 与 INT2NUM 相 似 
FIX2INT(o) 将 Fixnum 对 象 转 化 为 int 类 型 


FIX2LONG(o) 将 Fixnum 对 象 转化 为 Iong 类 型 


NUM2INT(o) 将 Fixnum 对 象 或 者 Bignum 对 象 转 化 为 int 类 型 


NUM2LONG(o) 将 Fixnum 对 象 或 者 Bignum 对 象 转 化 为 Jong 类 型 


Strings 
与 C 字 符 串 和 Ruby 字 符 串 相关 的 一 些 api 有 : 


接口 
VALUE rb_str_new(const char *ptr, long len) 
VALUE rb_str_ new_cstr(const char *ptr) 
char*rb_string_value_cstr(volatile VALUE*) 


char *StringValueCStr(VALUE) 


Arrays 
与 数组 相关 的 一 些 api : 


接口 
VALUErb_ary_new(void) 
VALUE rb_ary_push(VALUE ary, VALUE item) 


void rb_ary_store(VALUE ary, long idx, VALUE val) 


Hashes 
与 散 列 表 相 关 的 一 些 api : 


接口 
VALUE rb_hash_new() 新 建 一 个 散 列 表 


VALUE 
rb_hash_aset(VALUE 


hash, VALUE key, 设 证 键 什 
VALUE val) 

VALUE 

rb_hash_aref(VALUE 获取 一 个 键 的 值 


hash, VALUE key) 


void 
rb_hash_foreach(VALUE 
hash, int (*callback) 


描述 
将 ptr 指 针 指向 的 长 度 为 len 的 字符 串 转 化 为 Ruby 的 字符 串 对 象 
将 ptr 指 针 指 向 的 字符 串 转化 为 Ruby 的 字符 串 对 象 
将 Ruby 的 字符 串 对 象 转 化 为 C 的 字符 串 


rb_string_value_cstr 对 应 的 宏 


撕 间 


学 


创建 新 数组 
在 数组 结尾 插入 新 的 值 
在 idx 的 位 置 插入 新 的 值 


吉 
学 


通 历 散 列 表 ，callback 格 式 为 (*callback)(VALUE key, VALUE val, VALUE in)。 同 时 它 
的 返回 值 为 ST_CONTINUE 则 表示 正常 操作 ; 为 ST_STOP 则 停止 青 历 ; 为 


ST_DELETE 则 删除 当前 的 键 值 ; 为 ST_CHECK 则 检查 在 此 操作 过 程 中 该 散 列 表 是 否 
人 已 被 修改 ， 如 果 被 修改 则 停止 直 历 。 


Blocks && Callbacks 


代码 块 : 


intrb_block_given_p(void) 


VALUE rb_yield(VALUE); 


描述 
如 果 传递 了 代码 块 则 返回 1, 否则 返回 0 
Ruby 中 的 yield 功 能 


VALUE rb_yield_values(int n, ...); 同上 


VALUE rb_yield_values2(int n, const VALUE *argv); 同上 


Proc(lambdal) : 


接口 描述 
VALUE rb_proc_new(VALUE (*func)(ANYARGS), VALUE val) 创建 Proc 对 象 
VALUE rb_proc_call(VALUE self VALUE argS) 调用 Proc 对 象 


以 上 是 列 出 了 一 些 常用 的 api 接 口 ， 这 些 内 容 在 Ruby 的 文档 中 也 没有 介绍 ， 基 本 上 都 是 在 ruby.h 文件 和 intern.h 文件 中 找到 
的 。 这 里 再 发 下 牢骚 ， 感 觉 还 是 Python 的 文档 详细 啊 。 





关于 这 些 api 的 例子 可 以 参考 本 章 的 示例 。 


EL 
[= 


当 程 序 执行 出 错时 通常 的 做 法 是 抛 出 一 个 异常 ， 这 个 异常 既 可 以 是 内 建 的 异常 类 型 也 可 以 是 自 定义 的 异常 类 型 。 


内 建 异 常 类 
内 建 的 异常 类 型 如 下 : 


e rh_eException; 

e rb_eStandardError; 
e rhb_eSystemExit; 

e rhb_elnterrupt; 

e rb_eSignal; 

e rb_eFatal; 

e rb_eArgError; 

e rb_eEOFError; 

e rb_elndexError; 

e rh_eStoplteration; 

e rb_eKeyError; 

e rb_eRangeError; 

e rb_elOError; 

e rb_eRuntimeError; 

e rb_eSecurityError; 

e rh_eSystemCallError; 
e rb_eThreadError; 

e rh_eTypeError; 

e rb_eZeroDivError; 

e rb_eNotlmpError; 

e rb_ eNoMemError; 

e rb_eNoMethodError; 
e rb_eFloatDomainError; 
e rb_eLocalJumpError; 
e@ rh_eSysStackError; 
e rh_eRegexpError; 

e rb_eEncodingError; 
e rb_eEncCompatError; 
e rb_eScriptError; 

e rb_ eNameError; 

e@ rb_eSyntaxError; 

e rb_eLoadError; 

e rb_eMathDomainError; 


抛 出 异 帝 


通常 自 定义 异常 类 型 是 rb_eException 或 者 rb_estandardError 的 子 类 。 先 使 用 rb_define_class 定义 一 个 异常 类 型 ， 
己 
下 


抛 出 异常 的 方法 : 


e void rb_raise(error_class, error_string, …) 这 是 比较 常用 的 一 个 方法 ; 
e void rb_sys_fail(error_string) 根据 errno 抛 出 一 个 异常 ; 


其 中 rb_raise(error_class, error_string, ...) 的 作用 和 与 ruby 中 的 raise Error, string 相同 。 


然 


nt 


后 再 抛 


异 剃 处 理 


在 Ruby 中 可 以 使 用 rescue 捕获 一 个 异常 ， 在 C 代 码 中 与 之 对 应 的 函数 为 : 


ee rb_rescue(cb, cb_args, rescue_cb, rescue_argS) 
e rb_ensure(cb, cb_args,ensure_cb, ensure_args) 


rb_rescue 方法 对 应 ruby 的 rescue ， 它 的 四 个 参数 依次 是 ， cb : 要 执行 的 操作 ， 格 式 声明 为 VALUE cb(VALUE args) ; 
cb args : 传递 给 cb 画 数 的 参数 ; rescue_cb : 出 现 异常 时 处 理 异 常 的 回调 男 数 ， 格 式 声明 为 VALUE rescue_cb(VALUE args， 
VALUE err) ; rescue args : 传递 给 rescue cb 男 数 的 参数 。 


转化 为 ruby 的 语法 如 下 : 


begin 
cb(cb_args) 
rescue 
rescue_cb(rescue_args) 
end 


rb_ensure 方法 对 应 ruby 的 ensure ， 与 rb_rescue 类 似 。 ensure_cb 格式 声明 为 VALUE ensure_cb(VALUE args) 


转化 为 ruby 的 语法 如 下 : 


begin 
cb(cb_args) 
ensure 
ensure_cb(ensure_args) 
end 


Throw/Catch 


e rh_catch(constchar*, VALUE(*)(ANYARGS), VALUE) 
e rh_throw(constchar*, VALUE) 


rb_catch 方法 的 三 个 参数 分 别 为 : 要 catch 的 代码 块 名 称 ; catch 的 回调 画 数 ; 回调 参数 。 rb_throw 方法 的 两 个 参数 分 别 
为 : 返回 的 catch 代 码 块 名 称 ; 返回 值 。 


关于 异常 的 用 法 可 以 参考 本 章 的 示例 。 


结构 体 封装 && 内 存 管理 


前 面 介绍 过 在 C 扩 展 中 使 用 rb_define_class_under 定义 自 定 义 类 。 而 且 如 果 要 定义 一 些 变 量 的 话 也 可 以 使 用 rb_iv set 定义 实 
例 变量 ， 以 及 使 用 rb_define_variable 或 者 rb_global_variable 定义 全 局 变量 。 通 过 这 种 方法 可 以 实现 Ruby 与 C 共享 数据 。 
介绍 另 一 种 共享 数据 的 方法 一 一 封装 结构 体 。 





十 十 站 十 
结构 体 封 装 
在 Python 的 C 扩展 中 ， 定 义 一 个 自 定义 类 就 是 通过 定义 一 个 结构 体 来 模拟 实现 的 。 


在 Ruby 中 定义 了 几 个 有 用 的 宏 可 以 方便 的 对 结构 体 进 行 封装 。 


VALUE Data Wrap_Struct(VALUE class, void (*mark)(), void (*free)(), void *ptr); 
VALUE Data_ Make Struct(VALUE class, c-type, void (*mark)(), void (*free)(), c-type *ptr); 
Data_Get_Struct(VALUE obj,c-type,c-type *); 


Data_Wrap_Struct 是 将 C 的 数据 类 型 ptr 进行 封装 ， 并 返回 一 个 Ruby 类 型 的 对 象 。 该 对 象 是 对 应 的 C 类 型 为 T DATA ， 对 
应 的 Ruby 类 型 为 class 。 
Data_Make_Sstruct 首先 分 配 内 存 空 间 ， 然 后 执行 Data_Wrap_Struct 操作 。 


Data_Get_Struct 获取 原始 数据 的 指针 。 


内 存 分 配 


如 果 需 要 在 扩展 程序 中 申请 内 存 空间 来 存储 内 容 ， 可 以 直接 使 用 C 的 原生 方法 : malloc 、 realloc 、 calloc 。 不 过 这 样 的 
话 就 需要 记得 手动 释放 申请 的 内 存 ， 以 免 出 现 内 存 泄漏 。 为 了 方便 起 见 还 是 推荐 使 用 Ruby 定义 的 几 个 api: 


e ALLOC(type) 分 配 type 类 型 大 小 的 空间 ， 并 返回 type 类 型 的 指针 

e ALLOC_N(type, num) 分 配 hum 个 type 类 型 大 小 的 空间 ， 并 返回 type 类 型 的 指针 

e REALLOC_N(var, type, num) 将 var 指 向 的 空间 重新 分 配 为 num 个 type 类 型 大 小 的 空间 ， 并 返回 type 类 型 的 指针 
这 几 个 api 与 原生 的 C 方 法 功能 类 似 ， 只 是 内 存 的 申请 和 释放 都 是 由 Ruby 进 行 管理 ， 而 不 是 操作 系统 系统 。 


注意 : 使 用 以 上 方法 申请 的 内 存 得 使 用 xfree 进行 释放 。 

口 

示例 程序 

接 下 来 通过 一 个 例子 来 进行 讲解 。 首 先 声 明 一 个 结构 体 类 型 : 


typedef struct { 
int i; 
} cMyStruct; 


cTest = rb_define_class("MyStruct", rb_cObject); 


接着 在 类 的 new 方法 内 部 执行 操作 ， 将 该 结构 体 进行 封装 : 


cMyStruct *ptr = ALLOC(cMyStruct); 
VALUE tdata = Data_ Wrap_Struct(class, 0, t_free, ptr); 


现在 可 以 在 其 他 地 方 访问 该 结构 体 : 


cMyStruct *ptr; 
Data_Get_ Struct(self, cMyStruct, ptr); 


完成 的 例子 代码 可 以 从 https://github.com/wusuopu/ruby-c-extension-sample 获取 到 。 


SWIG && FFI 


在 开头 有 说 过 直接 使 用 C 来 编写 Ruby 扩 展 的 方法 可 能 显得 略 有 些 过 时 了 ， 因 为 还 有 其 他 更 加 方便 的 方法 可 以 让 Ruby 调 用 C 的 
库 。 本 章 就 简单 的 介绍 一 下 另外 两 个 工具 一 swig 和 看。 


SWIG 


SWIG 是 一 个 开发 工具 ， 能 够 将 C、C++ 与 多 种 语言 进行 连接 。 如 : PHP、Python、Perl、Ruby 等 。 

使 用 SWIG 的 好 多 是 只 需要 写 一 份 代码 就 可 以 实现 在 多 种 语言 中 调用 ; 而 缺点 是 需要 学 习 SWIG 自 己 的 编程 语法 。 
以 下 是 摘自 官网 的 一 个 例子 。 

首先 下 载 安装 SWIG: http:/www.swig.org/download.html 


然后 新 建文 件 example.c : 


/*File :example.c*/ 
#include <time.h> 
double My_variable = 3.0; 


int fact(int n) { 
famee ll) returml: 
else return n*fact(n-1); 


; 


int my_mod(int x, int y) { 
return (x%y); 


3 


char *get time!() 

i 
time t ltime; 
time(&ltime); 
return ctime(&ltime); 


} 


example.i : 


* example.i */ 

%module example 

%{ 

/* Put header files here or function declarations like below */ 
extern double My _variable; 

extern int fact(int n); 

extern int my_mod(int x, int y); 

extern char *get time(); 

%} 


extern double My _variable; 
extern int fact(int n); 

extern int my_mod(int x, int y); 
extern char *get time(); 





程序 编写 完成 之 后 ， 如 果 是 要 编译 成 Python 扩展 则 执行 命令 : 


swig -python example.i 
gcc -cexample.c example_wrap.c -l/usr/include/python2.7 
ld -shared example.o example_wrap.o -0 _example.so 


如 果 要 编译 在 Ruby 扩展 则 执行 命令 : 


swig -ruby example.i 
gcc -cexample.c example_wrap.c -Musrinclude/ruby-2.1.0/ -l/usr/include/ruby-2.1.0/i1686-linux 
ld -shared example.o example_wrap.o -0 example.so 


最 后 通过 一 个 程序 来 测试 一 下 结果 : 


require './example.so' 


puts Example.fact(5) 
puts Example.my_mod(7, 3) 
puts Example.get_time() 


FFI 


FFI 是 一 个 可 以 直接 加 载 动 态 链接 库 的 工具 。 使 用 Ruby-FFI 就 可 以 很 方便 的 调用 库 的 方法 。 


同样 的 ， 以 下 也 是 摘自 官方 的 例子 。 首 先 安 装 伯 : 


[sudo] gem install ffi 


或 者 下 载 源 代码 进行 安装 : https://github.com/ffi/ffi 


然后 运行 一 个 测试 程序 : 


require ffi' 


module MyLib 

extend FFl::Library 

fhalibee: 

attach_function :puts, [ :string ], :int 
end 


MyLib.puts 'Hello, World using libc!’ 


这 个 例子 是 在 Ruby 中 直接 调用 libc 库 的 puts 方法 。 结 果 应 该 是 可 以 看 到 输出 字符 串 : "Hello, World using libe!" 


RDoc && GEM 


前 面 几 章 介 绍 了 ruby 扩展 的 开发 方法 ， 最 后 再 来 介绍 两 个 有 用 的 工具 一 一 RDoc 和 GEM。 


RDoc 


RDoc 是 ruby 的 一 款 文档 生成 工具 ， 它 可 以 通过 代码 中 特殊 格式 的 注释 来 生成 文档 。 
RDoc 是 随 着 ruby 安装 的 ， 因 此 不 需要 再 进行 额外 安装 。 
接 下 来 准备 使 用 第 2 章 的 例子 ， 为 其 添加 文档 注释 。 


首先 在 rb_define_module 语句 之 前 添加 模块 注释 : 


性 
Document-module: MyTest 





C 扩 展 的 MyTest 模块 
3 
mTest = rb_define_module("MyTest"); 


然后 在 rb_define_class_under 语句 前 添加 类 注释 : 


* 
Document-class: MyTest 


MyTest 模块 下 的 MyTest 类 ， 


cTest = rb_define_class_under(mTest, "MyTest", rb_cObject); 


接着 就 可 以 使 用 rdoc 命 命 来 生成 文档 了 ， 生 成 HTML 格式 的 文档 : 


$ rdoc --main README.rdoc -o doc/site/api README.rdoc ext/my test.c 


生成 fi 格式 的 文档 : 


$ rdoc --main README.rdoc -o doc/ri -f ri README.rdoc ext/my _test.c 


为 了 方便 起 见 ， 可 以 为 RDoc 添加 一 个 rake 任务 。 在 Rakefile 中 添加 如 下 内 容 : 


require "rdoc/task' 
RDOC FILES = FileList["README.rdoc", "ext/my test.c"] 


Rake::RDocTask.new do |rd| 
rd.main = "README.rdoc" 
rd.rdoc_dir = "doc/site/api" 
rd.rdoc files.include(RDOC FILES) 
end 


Rake::RDocTask.new(:ri) do |rd| 
rd.main = "README.rdoc" 
rd.rdoc_dir = "doc/ri" 
rd.generator = "ri" 
rd.rdoc files.include(RDOC FILES) 

end 


现在 就 可 以 分 别 使 用 rake rdoc 命令 和 rake ri 命令 来 生成 HTML 格式 和 ri 格式 的 文档 了 ; 然后 分 别 使 用 rake clobber_rdoc 


命 伟 和 rake clobber_ri 命令 来 删除 已 生成 的 文档 文件 。 


局 


江 


上 只 是 一 个 简单 的 介绍 ， 关 于 在 C 扩 展 中 使 用 RDoc， 可 以 参考 文档 : http://docs.seattlerb.org/rdoc/RDoc/Parser/C.html 


GEM 


GEM 是 ruby 的 包 管 理工 具 ， 类 似 于 python 的 pip。 我 们 扩展 程序 开发 完成 之 后 可 以 通过 GEM 打包 并 与 其 他 人 分 享 。 
如 果 你 的 系统 中 没有 安装 GEM 的 话 ， 可 以 通过 这 个 地 址 下 载 安 装 : http://rubygems.org/pages/download 


首先 在 项 目 根 目录 下 创建 一 个 新 文件 .gemspec 


SPEC = Gem::Specification.new do |s| 
s.name = "example" 
s.version = "1.0" 
s.date = '2014-08-21' 
s.summary = "C bindings" 
s.description = "C Bindings" 
s.authors = ["Long Changjin"] 
s.email = ["admin@longchangjin.cn"] 
s.files = ["Rakefile", "COPYING", "NEWS", "README.rdoc", "ext/my _test.c", "ext/app.rb", "ext/extconf.rb"] 
s.homepage = "http://www.xefan.com/" 
s.required_ruby_version = '>= 2.1.0' 
s.extensions = "ext/extconf.rb" 

end 


然后 执行 命令 gem build .gemspec 生成 gem 包 。 在 当前 目录 下 应 该 会 生成 一 个 名 为 example-1.0.gem 的 文件 。 如 果 想 到 与 他 
人 分 享 该 gem 包 ， 可 以 执行 命 分 gem push example-1.0.gem 将 该 文件 上 传 。 


